package com.surekam.mnai.service;

import java.util.List;

import com.surekam.mnai.entity.LoadPattern;
import com.surekam.mnai.model.MobileNumberAttribution;

/**
 * 手机归属地服务接口
 * 这个接口的现实类在操作出现异常的时候，返回null,否则返回成功后的对象【添加方法除外，当出现像添加已有数据时【抛出异常】。构成数据链的模式
 * 
 * @author caoxu
 */
public interface IMobileNumAttributionService {

	/**
	 * 添加一个手机归属地信息
	 * 
	 * @param targetData
	 *            要添加的数据
	 * @return 成功返回添加的数据模型，否则 null
	 * 
	 * @throws ServiceException
	 *             添加操作失败 如：添加已有数据
	 */
	public MobileNumberAttribution addAttribution(
			MobileNumberAttribution targetData) throws ServiceException;

	/**
	 * 删除手机归属地的记录
	 * 
	 * @param targetData
	 *            要删除的记录
	 * @return 返回删除的对象(不包含数据id值)， 删除失败返回 null
	 */
	public MobileNumberAttribution delAttribution(
			MobileNumberAttribution targetData);

	/**
	 * 更新手机归属地的记录
	 * 
	 * @param targetData
	 * 
	 * @return 返回更新后的数据记录， 否则返回null
	 */

	public MobileNumberAttribution updateAttribution(
			MobileNumberAttribution targetData);

	/**
	 * 选择一个电话号码的归属信息 输入的数字长度必须是7-11
	 * 
	 * @param telNum
	 *            要得到的手机号码
	 * @return 有记录则返回完整记录 否则null
	 * 
	 * @throws NumberFormatException
	 *             电话号码长度小于7
	 */
	public MobileNumberAttribution load(String telNum)
			throws NumberFormatException;

	/**
	 * 返回所有的数据集合， 数据量很大时不推荐使用此方法
	 * 
	 * @return
	 */
	public List<MobileNumberAttribution> listAll();

	/**
	 * 返回一个起始id到(id+size)区间的数据记录
	 * 当id-(id+size)中的数据有id不连续时，size+1.到最后返回的集合数据大小为size,假如有数据
	 * 
	 * @param startID
	 *            起始id
	 * @param size
	 *            返回的集合数据容量
	 * @return
	 */
	public List<MobileNumberAttribution> listBySection(String startID, int size);

	/**
	 * 根据选择模式选取数据 可用1种模式 1.LoadPattern.CITY
	 * 
	 * @param term
	 *            在根据特定模式下的选择条件
	 * @param pattern
	 *            选择模式
	 * @return 返回数据集合
	 */
	public List<MobileNumberAttribution> loadsByPattern(String term,
			LoadPattern pattern);
}
